Back to Main Menu

ESRI Integration Configuration

Introduction

The assetic-esri python package provides a set of tools that can be used in the ESRI desktop environments (ArcMap and ArcGIS Pro) to create/update assets in Assetic and to update the corresponding feature in ESRI with the Assetic asset ID.  The feature spatial definition in ESRI can also be copied to Assetic so that the the Assetic map and spatial search tools can be used with the asset.

Configuration of assetic_esri tools

Two configuration files are required.  The default implementation of the integration expects these files to be located in a folder named 'Assetic' within the users roaming profile folder.  The roaming profile folder location is defined by the Windows system environment variable APPDATA.  The simplest way to navigate to this folder is to type %APPDATA% in Windows Explorer and hit enter:

The configuration files to create in the folder %APPDATA%\Assetic are:

1. An Assetic REST API authentication file.  This is used to define your connection details for your Assetic environment.  Refer to the article Assetic-Python-SDK-Quick-Start for the structure and content of this file.  The default name to use for this file is 'assetic.ini'.
2. An XML translation configuration file.  The default name to use for this file is 'arcmap_edit_config.xml':

• logfile – the name of the log file to write messages and exceptions to
• loglevel – the Python log level name, e.g. ‘debug’ or ‘info’. Debug will show a far greater level of detail and is used when first testing the implementation, and in problem solving
• Asset Category to ESRI layer field mapping
  • Define the Assetic asset category that the layer corresponds to
  • Define the field in ArcMap that corresponds with the Assetic unique id
  • Define the initial status of the created asset
  • Define whether to upload the spatial feature to Assetic
  • Define fields in the layer that correspond to fields in Assetic
  • Define hardcoded values to use instead of field map layer field values
  • Optionally define components to be created against the asset
    • Optionally define dimensions to be created against the component
  • Optionally define Functional Location to associate asset with
  • Define the record count threshold above which the integration uses Data Exchange to apply asset updates rather than per asset updates.  The default is 250 records.
• Functional Location to ESRI layer field mapping

Sample XML Configuration File

The XML sample file "arcmap_edit_config.xml" includes comments that explain the configuration structure and usage.

Download Sample XML Hint: You may need to right click and 'Save As' to download

XML Configuration File Structure

The following section details the configuration file structure using the sample configuration file mentioned above.

General Configuration Settings

The following settings allow the location of the log file and the log level to be set.

Python log levels are listed in the python help: logging

<logfile>c:\temp\logfile.log</logfile>
<loglevel>info</loglevel> 

Bulk Update Threshold

The threshold after which a selection of assets is bulk updated is by default 250. When there are 250 or more features selected for update the integration swaps from a per-record update to a Data Exchange update which is a more efficient approach for a large number of records.

The threshold can be modified by setting the property LayerTools.bulk_threshold to an integer value.

This threshold was introduced in assetic_esri package version 1.1.1.1

In the example below it is set to 100

<bulk_threshold>100</bulk_threshold>

Layer Settings

Configuration is per ESRI layer, as defined by the layer name in the sample below. In this instance the layer name is 'UnsealedRoads'.   Within the configuration file multiple 'layer' nodes may be defined, with the 'name' differentiating each node.

<layer name="UnsealedRoads">

Within this layer node is settings specific to the layer.

The following nodes can be defined:

• category
  • This is mandatory.  Defines the Assetic Asset Category to associate with the layer.  Use the name of the category as shown in the Assetic application UI
• creation_status
  • When creating an asset for this layer, indicate what the status should
    be for the new asset. If omitted the default is 'Active'. Can be one of:
    • Active
    • Proposed
    • Notional Asset
• upload_feature
  • Boolean flag indicating whether to maintain a copy of the spatial feature in Assetic.  If 'True' the spatial feature will be created in Assetic on asset creation, and updated when the feature is updated.
• resolve_lookups
  • Boolean flag indicating whether to use the field's coded domain values (False) or to resolve the field coded values to their respective description via lookup (True).
• multiple_work_group_separator
  • Defines a character to use to separate multiple values, if a layer field has been mapped to specify multiple workgroups for assets. If not explicitly specified for a layer, the default separator character of comma (,) is applied.

<category>Roads</category>
<creation_status>Active</creation_status>
<upload_feature>True</upload_feature>
<resolve_lookups>True</resolve_lookups>
<multiple_work_group_separator>,</multiple_work_group_separator>

Asset Configuration

The following settings apply to asset creation/update.

Core Fields

The node 'corefields' is used to define the field translation between the ESRI layer and the Assetic asset 'core' fields as listed in the article Asset Integration Overview

In the XML example below the field translations are:

<corefields>
 <!--Name of the layer field name used to record the assetic asset identifier-->
 <asset_id>assetid</asset_id>

 <asset_name>assetname</asset_name>
 <asset_class>class</asset_class>
 <asset_sub_class>subclass</asset_sub_class>
 <asset_type>type</asset_type>
 <asset_sub_type>subtype</asset_sub_type>
 <asset_external_identifier>externalid</asset_external_identifier>
 <asset_security_group>securitygroup</asset_security_group>
 <asset_criticality>criticality</asset_criticality>
</corefields>

NOTE  the names are as per the Python SDK asset model where uppercase characters are instead replaced with an underscore and a lowercase character (e.g. "AssetName" is replaced with "asset_name").

Asset Id Configuration

Within the Assetic application there are 2 options for how the Asset Id is generated. These 2 options apply per Asset Category, and can therefore differ between Asset Categories.  The article Asset Auto ID Generation further outlines these 2 options.

• Asset Id Auto-generation:
  • Within the Assetic application a system administrator sets the Asset Category to have the asset Id auto-generated.  When the asset is created no asset Id needs to be supplied.  On creation of the asset Assetic generates a unique asset id which is returned to the user, and displayed against the asset.
  • In this scenario if you define a field in ESRI that translates to Assetic asset Id the integration will populate the ESRI field with the Assetic asset Id upon asset creation by the integration.  It is not mandatory to provide a field translation for asset Id.
• User Defined Asset Id:
  • If you wish to generate the Asset Id externally to Assetic, and provide the asset Id upon asset creation then asset_id becomes a mandatory 'corefield' in the configuration.  This field will need to be populated within ESRI with a unique asset Id.

The 'Asset Id' is a user visible unique identifier for the asset.  The Assetic REST API's utilise a hidden Id that uniquely identifies the asset.  This hidden Id is a system generated GUID and is always returned by the Assetic REST API whenever an asset is created.  This Id can optionally be recorded against the feature in ESRI.  If using a user defined asset Id the integration can optionally update the ESRI feature with the Id upon asset creation.  This assists with establishing which features in ESRI have a corresponding asset in Assetic.

In the following XML configuration example the ESRI field 'assetguid' will be updated with the Assetic Id upon asset creation.

<corefields>
 <!--Name of the layer field name to record the assetic GUID asset identifier-->
 <id>assetguid</id>
</corefields>

Asset Name Configuration

The Asset Name is mandatory, however it does not need to be unique.  The asset name can therefore be defined in either 'corefields' as a field translation to an ESRI field, or defined in 'coredefaults' with a default name.

Core Defaults

The node 'coredefaults' allows hard coded values to be applied to core asset fields upon asset creation/update.

In the example below the assets associated with the ESRI layer will all have a default Work Group of 'Transport'. Multiple work groups for the asset have also been specified, which are provided in a delimited manner where each work group has been separated by a comma (,).

<coredefaults>
 <asset_work_group>Transport</asset_work_group>
 <work_groups>Transport,Fleet,Services</work_groups>
</coredefaults>

The delimiter character used to separate work group values can be modified as required using the "multiple_work_group_separator" layer setting as outlined in the Layer Settings section above.

Work Groups Configuration

If specifying an Assetic work group mapping for a layer, the XML configuration for the integration allows for defining either a single 1-to-1 linkage of a work group for an asset, or alternatively also provides the option for the integration to link an asset to a list of multiple work group values to utilise the Assetic multiple work group functionality for assets. This is achieved by parsing a collection of work group values, which have been delimited by a particular character, in order to create/update an asset and assign it to more than 1 work group.

NOTE  Note: The XML multiple work group configuration functionality requires v2023.16.1.4 or greater of the Assetic Python SDK. Please refer to the 'Installation of assetic_esri package' section of the ESRI Integration Introduction article for more information on how to upgrade Assetic packages.

For work group configurations in the XML file, the core field elements "asset_work_group" and "work_groups" are used, which are outlined below:

• asset_work_group
  • the asset's default work group
• work_groups
  • a delimited list of one or more work groups

Single Workgroup

For situations where an asset will have a 1-to-1 to just a single work group, and the workgroup is thereby also the default, only the XML element "asset_work_group" needs to be mapped and populated within the XML configuration. The "work_groups" XML element does not need to be provided. In this scenario, a single work group value that has been specified as the default will be applied as both the default and also as a single workgroup value for the asset's work groups list during creation or updates.

Multiple Workgroups

For mapping and specifying an asset to be assigned more than 1 work group, both of the 'asset_work_group' and 'work_groups' XML elements must be included in a layer's configuration to utilize the multiple work group functionality. The value specified as the asset's default work group should also be included as part of the overall delimited list of multiple work group values.

Depending on the desired character to be used for the separation of work group values, the "multiple_work_group_separator" setting at the layer level can be utilized. By default, the separator character is set to comma (,) if it this element has not been specified within the XML. If included in the XML layer settings, a custom separation character can be specified as required if the default value of comma is not suitable.

Attribute Fields Configuration

Assetic 'non-core' attribute field translations are defined in the XML node 'attributefields'. The name of each child node is the Assetic asset attribute name with the value being the ESRI field name. The attribute field names, unlike the core field names, are represented as the case sensitive names in Assetic. e.g Zone remains as Zone
The XML child node name is the Assetic internal attribute field name (not the field label).
Refer to the 'Asset Attribute Fields' section of the Asset Integration Overview article to understand how to obtain the Assetic asset attribute field names.

In the example below the ESRI field 'ZONING' translates to the Assetic asset field 'Zone'

<attributefields> 
 <Zone>ZONING</Zone>
</attributefields>

Attribute Defaults Configuration

The XML node 'attributedefaults' allows hard coded values to be applied to 'non-core' asset attribute fields upon asset creation/update.

In the example below the assets associated with the ESRI layer will all have a Work Group of 'Transport'.

In the example below the same comment is applied to all assets in the ESRI layer.

<attributedefaults>
 <Comment>Look at me! I created a new asset.</Comment>
</attributedefaults>

Asset Component

The configuration file allows for one or more components to be created/updated for an asset.

The 'component' node is optional and may be omitted from the XML if components are not required.

Each 'component' node within the 'layer' represents a different component.

The combined component type and component name makes each component unique, and therefore this combination must not be repeated for another component configuration within the same layer configuration.

The list of component fields is provided in the 'Components' section of the article Asset Integration Overview.

NOTE  the Assetic field names to use in the configuration are as per the Python SDK component model where uppercase characters are replaced with and underscore and the lowercase character. e.g DesignLife=design_life

Component Fields Configuration

The node 'componentfields' is used to configure ESRI fields that correspond to an Assetic component field.
The node name is the Assetic component field name (python format) and the node value
is the field name in the layer.

The following example defines the ESRI fields 'SURFACELIFE' and 'SURFACEMATERIAL' translation to Assetic component 'DesignLife' and 'MaterialType'

<componentfields>
 <design_life>SURFACELIFE</design_life>
 <material_type>SURFACEMATERIAL</material_type>
</componentfields>

Component Defaults Configuration

The XML node 'componentdefaults' allows hard coded values to be applied to component fields.

This allows the ComponentType and Label to be set which is important because it is the combination of component type and label (component name) that differentiates this component from any other component created against the asset. 

The component 'Label' field is the component name displayed in Assetic.  

In the XML example below the field translations are:

<componentdefaults>
 <label>Surface</label>
 <component_type>Surface Main</component_type>
 <dimension_unit>Metre</dimension_unit>
 <network_measure_type>Length</network_measure_type>
 <financial_class_name>Roads</financial_class_name>
 <financial_sub_class_name>Sealed Roads</financial_sub_class_name>
</componentdefaults>

Asset Dimension Configuration

The configuration file allows for one or more dimensions to be created/updated for a component.

The 'dimension' node is optional and may be omitted from the XML if dimensions are not required.

Each 'dimension' node within the component represents a different dimension.

The combination of dimension record_type, network measure type, and shape name makes each dimension unique, and therefore must not be repeated for another dimension configuration within the same component configuration.  A dimension may be created without a shape, in which case 1 dimension record without a shape per network measure type and record type is supported, along with other dimension records that have unique shapes.

The list of dimension fields is provided in the 'Dimensions (Network Measure)' section of the article Asset Integration Overview.

NOTE  the Assetic field names to use in the configuration are as per the Python SDK component model where uppercase characters are replaced with and underscore and the lowercase character. e.g NetworkMeasure=network_measure

Dimension Fields Configuration

The node 'dimensionfields' is used to configure ESRI fields that correspond to an Assetic dimension field.
The node name is the Assetic dimension field name (python format) and the node text value
is the field name in the layer.

In the example below the Assetic fields 'length' and 'width' are the node element names and the node text 'COMP_LEN' and 'WIDTH' are the ESRI layer field names.

<dimensionfields>
 <length>COMP_LEN</length>
 <width>WIDTH</width>
</dimensionfields>

Dimension Defaults Configuration

The XML node 'dimensiondefaults' allows hard coded values to be applied to dimension fields.

This allows the RecordType to be set which is important because it is this dimension record type that differentiates this dimension from any other dimension created against the component. 

In the XML example below the field translations are:

<dimensiondefaults>
 <unit>Square Metre</unit>
 <record_type>Info</record_type>
 <network_measure_type>Area</network_measure_type>
 <shape_name>Rectangle</shape_name>
 <length_unit>Metre</length_unit>
 <width_unit>Metre</width_unit>
</dimensiondefaults>

Address Configuration

The address of an asset is set via the address configuration.

If the address is not required then omit the following nodes from the configuration.
If defining address, 'country' is the minimum requirement.

Address Fields Configuration

The node 'addressfields' is used to configure ESRI fields that correspond to an Assetic address field.
The node name is the Assetic address field name (python format) and the node text value
is the field name in the layer.

In the XML example below the field translations are:

<addressfields>
 <street_number>HOUSE_NUMBER</street_number>
 <street_address>STREET_NAME</street_address>
 <city_suburb>SUBURB</city_suburb>
</addressfields>

Address Defaults Configuration

The XML node 'addressdefaults' allows hard coded values to be applied to dimension fields.
The node name is the Assetic address field name (python format) and the node text value
is the value to apply in Assetic

In the XML example below the field translations are:

 <addressdefaults>
   <state>Tauranga</state>
   <zip_postcode>23456</zip_postcode>
   <country>New Zealand</country>
 </addressdefaults>

Functional Location Association to Asset

The XML node 'functional_location' allows the asset to be associated with a functional location.

An asset may be associated with only 1 functional location.

The table below outlines the 3 GIS fields that may be used to define the association:

In the XML example below the field translations are:

 <functional_location>
   <functional_location_id>func_loc_fid</functional_location_id>
   <functional_location_name>func_loc_name</functional_location_name>
   <functional_location_type>func_loc_type</functional_location_type>
 </functional_location>

Functional Location

A new Functional Location may be created via a layer dedicated to Functional Location.

The XML configuration for Functional Location is at the same level as the Asset Configuration (it is not a child of the Asset Configuration).

All Functional Location configurations are defined in a node as shown below:

<operation action="Functional Location">

Within the "Functional Location" node each layer to Functional Location configuration is defined by specifying the layer name. In the example below the layer name is "local_govt_reserve":

<layer name="local_govt_reserve">

Like the Asset configuration, the Functional Location definition is broken into core fields and attribute fields, and supports fields from the GIS layer and hardcoded 'default' fields.

Core Fields

The node 'fl_corefields' is used to define the field translation between the ESRI layer and the Assetic Functional Location 'core' fields as listed in the article Asset Integration Overview

The core fields are:

 <fl_corefields>
   <id>FL_ID</id>
   <functional_location_id>FL_FID</functional_location_id> 
   <functional_location_name>FL_NAME</functional_location_name>
 </fl_corefields>

NOTE  the names are as per the Python SDK asset model where uppercase characters are replaced with and underscore and the lowercase character. e.g FunctionalLocationId=functional_location_id

Functional Location Id Configuration

Within the Assetic application there are 2 options for how the Functional Location Id is defined. These 2 options apply per Functional Location Type, and can therefore differ between Functional Location Type.  The article Functional Location Types further outlines these 2 options.

• Functional Location Id Auto-generation:
  • Within the Assetic application a system administrator sets the Functional Location Type to have the Functional Location Id auto-generated.  When the Functional Location is created no Functional Location Id needs to be supplied.  On creation of the Functional Location Assetic generates a unique Functional Location id which is returned to the user, and displayed against the Functional Location.
  • In this scenario if you define a field in ESRI that translates to Assetic Functional Location Id the integration will populate the ESRI field with the Assetic Functional Location Id upon Functional Location creation by the integration.  It is not mandatory to provide a field translation for Functional Location Id.
• User Defined Functional Location Id:
  • If you wish to generate the Functional Location Id externally to Assetic, and provide the Functional Location Id upon Functional Location creation then functional_location_id becomes a mandatory 'fl_corefields' in the configuration.  This field will need to be populated within ESRI with a unique Functional Location Id.

The 'Functional Location Id' is a user visible unique identifier for the Functional Location.  The Assetic REST API's utilise a hidden Id that uniquely identifies the Functional Location.  This hidden Id is a system generated GUID and is always returned by the Assetic REST API whenever an asset is created.  This Id can optionally be recorded against the feature in ESRI.  If using a user defined Functional Location Id the integration can optionally update the ESRI feature with the Id upon asset creation.  This assists with establishing which features in ESRI have a corresponding Functional Location in Assetic.

In the following XML configuration example the ESRI field 'fl_id' will be updated with the Assetic Id upon asset creation.

<fl_corefields>
 <id>FL_ID</id>
</fl_corefields>

Core Defaults

The node 'fl_coredefaults' allows hard coded values to be applied to core Functional Location fields upon Functional Location creation/update.

In the example below the Functional Location associated with the ESRI layer will all be in the Functional Location Type 'Park Site'.

<fl_coredefaults>
 <functional_location_type>Park Site</functional_location_type>
</fl_coredefaults>

Functional Location Name Configuration

The Functional Location Name is mandatory, and although it does not need to be unique the integration requires that the name is unique for the given Functional Location Type. 

Functional Location Type Configuration

The Functional Location Type is mandatory and must be defined in either 'fl_corefields' as a field translation to an ESRI field, or defined in 'fl_coredefaults' with a default name.  Typically it would only be defined as a field translation in 'fl_corefields' if the type differs between features within a layer.

Functional Location Attribute Fields Configuration

Assetic 'non-core' attribute field translations are defined in the XML node 'fl_attributefields'. The name of each child node is the Assetic Functional Location attribute name with the value being the ESRI field name. The attribute field names, unlike the core field names, are represented as the case sensitive names in Assetic. e.g 'GroupAssetComment' remains as 'GroupAssetComment'.

The XML child node name is the Assetic internal attribute field name (not the field label).
Refer to the 'Functional Location Attribute Fields' section of the Asset Integration Overview article to understand how to obtain the Assetic Functional Location attribute field names.

In the example below the ESRI field 'COMMENT' translates to the Assetic Functional Location field 'GroupAssetComment'

 <fl_attributefields>
   <GroupAssetComment>COMMENT</GroupAssetComment>
 </fl_attributefields>

Attribute Defaults Configuration

The XML node 'fl_attributedefaults' allows hard coded values to be applied to 'non-core' Functional Location attribute fields upon Functional Location creation/update.

In the example below the Functional Location associated with the ESRI layer will all have a vaue for 'Zone' of 'Zone 2'.

In the example below the same comment is applied to all assets in the ESRI layer.

 <fl_attributedefaults>
   <GroupAssetZone>Zone 2</GroupAssetZone>
 </fl_attributedefaults>